Release 10.1A: OpenEdge Development:
Progress Dynamics Basic Development

Running business logic procedures in Progress Dynamics

As Progress Dynamics supports a stateless environment, you must write business logic as concisely and as efficiently as possible. When your environment uses one or more AppServers, which is considered the norm, a call to a business logic procedure will ordinarily result in a connect to an AppServer session (activation), the running of the code, and then the disconnection from the AppServer session (deactivation).

If you run a procedure persistently on the AppServer, then you will bind the connection to the AppServer until you delete the persistent procedure. You must take extreme care not to bind AppServer connections unnecessarily, as doing so negates the scalability of Progress Dynamics applications.

While you should keep persistent procedures to a minimum, when you use them, you should use the standard Progress Dynamics mechanism for invoking business logic procedures on an AppServer. This is supported by the Progress Dynamics Session Manager, in order that business logic procedures can be initiated on the AppServer and then accessed from client application sessions in the most efficient way possible.

These Progress Dynamics business logic procedures are called Persistent Libraries of Internal Procedures (PLIPs). They are external procedures (.p files) that contain many internal procedures, run persistently (by a call to launchProcedure, normally handled by the Session Manager). The internal procedures usually relate to API calls relevant to a particular object. For example, a PLIP could be defined for various supporting logic for client updates. The internal procedures inside that PLIP could be called to validate particular parts of the client information or execute additional business logic, for example, when address information is changed.

If business logic must identify whether it is running locally or remotely, then you can check the session:remote flag and SESSION:PARAM = “REMOTE”. If either of these is true, then the code runs remotely (on an AppServer), otherwise it runs locally on the client. You must also check the session parameter, since when running in a WebSpeed environment, the session:remote flag returns as false.

All business logic in Progress Dynamics that must be run persistently must be run by a standard include file, called launch.i, that encapsulates calls to launchProcedure. This include file takes one or more of the named arguments listed in Table 11–1.

Table 11–1: launch.i named arguments 

Argument	Description
{&PLIP}	Physical procedure (PLIP) name, for example, ac\app\actaxplipp.p.
{&Iproc}	Internal procedure, for example, calculateTax or left undefined to just start the PLIP.
{&PList}	Parameter list, for example, (OUTPUT cTaxAmount) or left undefined for no parameters.
{&OnApp}	Run on AppServer flag YES, NO, or APPSERVER default = YES.
{&Partition}	AppServer partition name.
{&Perm}	Run permanently YES/NO, default = NO (do not let agent kill it).
{&AutoKill}	Auto kill PLIP after run; YES/NO, default = NO.
{&NewInstance}	New instance YES/NO, default = NO (use running instance if any).
{&Define-only}	YES = define the variables you need but take no other action.

The following rules apply to the use of launch.i:

Required logical arguments must be passed in unquoted as YES or NO. Other text arguments must be single quoted literals (for example, 'text') or unquoted variables. If the literals require spaces, they should be double quoted then single quoted (for example, '"text text"').
The only exception to the above rule is for the parameter list, which does not support a variable, so only double quotes must be used.
You can omit the internal procedure so you can manually run procedures in the PLIP. The PLIP handle is made available in hPlip, a standard Progress 4GL variable.
If the &OnApp parameter is not specified, it defaults to YES, which means that the procedure runs on the AppServer, if one is connected; otherwise it runs locally. Passing in APPSERVER causes the procedure to fail if the AppServer is not connected.
If the &OnApp parameter is not set to NO, then you can specify a partition that will be connected, if not already connected. If you do not specify a partition, it defaults to the standard AppServer partition and runs on the gshAppserver handle.
If the &Perm parameter is passed in as YES, then the procedure is not killed when the agent disconnects, leaving it running for other connections. This is not the norm.
If &AutoKill is set to YES, then following the run of the internal procedure in the persistent procedure, the PLIP is automatically closed. This is useful when you are running routines on an AppServer to ensure the connection does not remain bound.
If &NewInstance is set to YES, then it does not check for an already running instance of the PLIP to use. Instead, it runs a new version.

Following the use of the include file, the variable values noted in Table 11–2 will be defined and available.

Table 11–2: Variable values available 

Variable	Definition
hPlip	Handle of the PLIP that was run.
cPlipErrorButton	Error button chosen, if any.

If the run failed for any reason, the hPlip handle will be invalid and any errors will have been displayed, if possible:

/* All parameters passed */ {launch.i &PLIP = 'af/app/aftstplipp.p' &IProc = 'objectDescription' &PList = "(output cHello)" &OnApp = 'yes' &Partition = 'Progress Dynamics' &Perm = NO &Autokill = NO &NewInstance = NO &Define-only = NO}

/* Just required parameters passed accepting defaults for rest */ {launch.i &PLIP = 'af/app/aftstplipp.p' &IProc = 'objectDescription' &PList = "(output cDescription)"}

dynlaunch.i

This include file is only recommended for Appserver calls where the procedure handle is not need after the call. It encapsulates the dynamic call wrapper and, therefore, all dynamic call wrapper comments apply.

dynlaunch.i accepts a temp-table of call information. The call is then constructed from this information and invoked. This process does result in a performance overhead. It is recommended that users only use this call under the following conditions:

When making calls across the Appserver, where the benefits of reduced Appserver calls and an unbound connection outweigh the disadvantage of the overhead associated with the dynamic call.
When call parameters are only known run time.

When making calls across the Appserver, the call is constructed and invoked from a non-persistent procedure on the Appserver. The call results are stored in the temp-table, and returned to the user. This results in one Appserver call, with the agent not bound. Note that persistent procedure handles are not available to the client after the call has completed. If the user wishes to run a procedure persistently and use the procedure handle after the call, it is recommended that launch.i be used.